home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / glibmm-2.4 / glibmm / markup.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-04-20  |  15.3 KB  |  421 lines
  1. // -*- c++ -*-
  2. // Generated by gtkmmproc -- DO NOT MODIFY!
  3. #ifndef _GLIBMM_MARKUP_H
  4. #define _GLIBMM_MARKUP_H
  5.  
  6.  
  7. /* $Id: markup.hg,v 1.5 2005/01/21 12:48:05 murrayc Exp $ */
  8.  
  9. /* Copyright (C) 2002 The gtkmm Development Team
  10.  *
  11.  * This library is free software; you can redistribute it and/or
  12.  * modify it under the terms of the GNU Library General Public
  13.  * License as published by the Free Software Foundation; either
  14.  * version 2 of the License, or (at your option) any later version.
  15.  *
  16.  * This library is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19.  * Library General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU Library General Public
  22.  * License along with this library; if not, write to the Free
  23.  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24.  */
  25.  
  26.  
  27. #include <glibmm/error.h>
  28. #include <sigc++/sigc++.h>
  29.  
  30. #include <map>
  31. #include <glibmmconfig.h>
  32.  
  33. GLIBMM_USING_STD(map)
  34.  
  35. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  36. extern "C" { typedef struct _GMarkupParseContext GMarkupParseContext; }
  37. #endif
  38.  
  39.  
  40. namespace Glib
  41. {
  42.  
  43. /** @defgroup Markup Simple XML Subset Parser
  44.  *
  45.  * The Glib::Markup parser is intended to parse a simple markup format that's a
  46.  * subset of XML. This is a small, efficient, easy-to-use parser. It should not
  47.  * be used if you expect to interoperate with other applications generating
  48.  * full-scale XML. However, it's very useful for application data files, config
  49.  * files, etc. where you know your application will be the only one writing the
  50.  * file. Full-scale XML parsers should be able to parse the subset used by
  51.  * Glib::Markup parser, so you can easily migrate to full-scale XML at a later
  52.  * time if the need arises.
  53.  *
  54.  * Glib::Markup is not guaranteed to signal an error on all invalid XML;
  55.  * the parser may accept documents that an XML parser would not. However,
  56.  * invalid XML documents are not considered valid Glib::Markup documents.
  57.  *
  58.  * @par Simplifications to XML include:
  59.  *
  60.  * - Only UTF-8 encoding is allowed.
  61.  * - No user-defined entities.
  62.  * - Processing instructions, comments and the doctype declaration are "passed
  63.  *   through" but are not interpreted in any way.
  64.  * - No DTD or validation.
  65.  *
  66.  * @par The markup format does support:
  67.  *
  68.  * - Elements
  69.  * - Attributes
  70.  * - 5 standard entities: <tt>\& \< \> \" \'</tt>
  71.  * - Character references
  72.  * - Sections marked as <tt>CDATA</tt>
  73.  *
  74.  * @{
  75.  */
  76.  
  77. /** %Exception class for markup parsing errors.
  78.  */
  79. class MarkupError : public Glib::Error
  80. {
  81. public:
  82.   enum Code
  83.   {
  84.     BAD_UTF8,
  85.     EMPTY,
  86.     PARSE,
  87.     UNKNOWN_ELEMENT,
  88.     UNKNOWN_ATTRIBUTE,
  89.     INVALID_CONTENT
  90.   };
  91.  
  92.   MarkupError(Code error_code, const Glib::ustring& error_message);
  93.   explicit MarkupError(GError* gobject);
  94.   Code code() const;
  95.  
  96. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  97. private:
  98.   static void throw_func(GError* gobject);
  99.   friend void wrap_init(); // uses throw_func()
  100. #endif
  101. };
  102.  
  103.  
  104. /*! @var MarkupError::Code MarkupError::BAD_UTF8
  105.  * Text being parsed was not valid UTF-8.
  106.  */
  107. /*! @var MarkupError::Code MarkupError::EMPTY
  108.  * Document contained nothing, or only whitespace.
  109.  */
  110. /*! @var MarkupError::Code MarkupError::PARSE
  111.  * Document was ill-formed.
  112.  */
  113. /*! @var MarkupError::Code MarkupError::UNKNOWN_ELEMENT
  114.  * This error should be set by Glib::Markup::Parser virtual methods;
  115.  * element wasn't known.
  116.  */
  117. /*! @var MarkupError::Code MarkupError::UNKNOWN_ATTRIBUTE
  118.  * This error should be set by Glib::Markup::Parser virtual methods;
  119.  * attribute wasn't known.
  120.  */
  121. /*! @var MarkupError::Code MarkupError::INVALID_CONTENT
  122.  * This error should be set by Glib::Markup::Parser virtual methods;
  123.  * something was wrong with contents of the document, e.g. invalid attribute value.
  124.  */
  125.  
  126. /** @} group Markup */
  127.  
  128.  
  129. namespace Markup
  130. {
  131.  
  132. class ParseContext;
  133.  
  134. /** @ingroup Markup */
  135. typedef Glib::MarkupError Error;
  136.  
  137.  
  138. /** Escapes text so that the markup parser will parse it verbatim.
  139.  * Less than, greater than, ampersand, etc. are replaced with the corresponding
  140.  * entities.  This function would typically be used when writing out a file to
  141.  * be parsed with the markup parser.
  142.  * @ingroup Markup
  143.  * @param text Some valid UTF-8 text.
  144.  * @return Escaped text.
  145.  */
  146. Glib::ustring escape_text(const Glib::ustring& text);
  147.  
  148.  
  149. /** @addtogroup glibmmEnums Enums and Flags */
  150.  
  151. /** There are no flags right now. Pass <tt>Glib::Markup::ParseFlags(0)</tt> for
  152.  * the flags argument to all functions (this should be the default argument
  153.  * anyway).
  154.  * @ingroup glibmmEnums
  155.  * @par Bitwise operators:
  156.  * <tt>%ParseFlags operator|(ParseFlags, ParseFlags)</tt><br>
  157.  * <tt>%ParseFlags operator&(ParseFlags, ParseFlags)</tt><br>
  158.  * <tt>%ParseFlags operator^(ParseFlags, ParseFlags)</tt><br>
  159.  * <tt>%ParseFlags operator~(ParseFlags)</tt><br>
  160.  * <tt>%ParseFlags& operator|=(ParseFlags&, ParseFlags)</tt><br>
  161.  * <tt>%ParseFlags& operator&=(ParseFlags&, ParseFlags)</tt><br>
  162.  * <tt>%ParseFlags& operator^=(ParseFlags&, ParseFlags)</tt><br>
  163.  */
  164. enum ParseFlags
  165. {
  166.   DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0
  167. };
  168.  
  169. /** @ingroup glibmmEnums */
  170. inline ParseFlags operator|(ParseFlags lhs, ParseFlags rhs)
  171.   { return static_cast<ParseFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
  172.  
  173. /** @ingroup glibmmEnums */
  174. inline ParseFlags operator&(ParseFlags lhs, ParseFlags rhs)
  175.   { return static_cast<ParseFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
  176.  
  177. /** @ingroup glibmmEnums */
  178. inline ParseFlags operator^(ParseFlags lhs, ParseFlags rhs)
  179.   { return static_cast<ParseFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
  180.  
  181. /** @ingroup glibmmEnums */
  182. inline ParseFlags operator~(ParseFlags flags)
  183.   { return static_cast<ParseFlags>(~static_cast<unsigned>(flags)); }
  184.  
  185. /** @ingroup glibmmEnums */
  186. inline ParseFlags& operator|=(ParseFlags& lhs, ParseFlags rhs)
  187.   { return (lhs = static_cast<ParseFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
  188.  
  189. /** @ingroup glibmmEnums */
  190. inline ParseFlags& operator&=(ParseFlags& lhs, ParseFlags rhs)
  191.   { return (lhs = static_cast<ParseFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
  192.  
  193. /** @ingroup glibmmEnums */
  194. inline ParseFlags& operator^=(ParseFlags& lhs, ParseFlags rhs)
  195.   { return (lhs = static_cast<ParseFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
  196.  
  197.  
  198. /*! @var Markup::ParseFlags DO_NOT_USE_THIS_UNSUPPORTED_FLAG
  199.  * Flag you should not use.
  200.  */
  201.  
  202.  
  203. /** Binary predicate used by Markup::Parser::AttributeMap.
  204.  * @ingroup Markup
  205.  * Unlike <tt>operator<(const ustring& lhs, const ustring& rhs)</tt>
  206.  * which would be used by the default <tt>std::less<></tt> predicate,
  207.  * the AttributeKeyLess predicate is locale-independent.  This is both
  208.  * more correct and much more efficient.
  209.  */
  210. class AttributeKeyLess
  211. {
  212. public:
  213.   typedef Glib::ustring first_argument_type;
  214.   typedef Glib::ustring second_argument_type;
  215.   typedef bool          result_type;
  216.  
  217.   bool operator()(const Glib::ustring& lhs, const Glib::ustring& rhs) const;
  218. };
  219.  
  220.  
  221. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  222. class ParserCallbacks;
  223. #endif
  224.  
  225. /** The abstract markup parser base class.
  226.  * @ingroup Markup
  227.  * To implement a parser for your markup format, derive from
  228.  * Glib::Markup::Parser and implement the virtual methods.
  229.  *
  230.  * You don't have to override all of the virtual methods.  If a particular
  231.  * method is not implement the data passed to it will be ignored.  Except for
  232.  * the error method, any of these callbacks can throw an error exception; in
  233.  * particular the MarkupError::UNKNOWN_ELEMENT,
  234.  * MarkupError::UNKNOWN_ATTRIBUTE, and MarkupError::INVALID_CONTENT errors
  235.  * are intended to be thrown from these overridden methods. If you throw an
  236.  * error from a method, Glib::Markup::ParseContext::parse() will report that
  237.  * error back to its caller.
  238.  */
  239. class Parser : public sigc::trackable
  240. {
  241. public:
  242.   typedef std::map<Glib::ustring, Glib::ustring, Glib::Markup::AttributeKeyLess> AttributeMap;
  243.  
  244.   virtual ~Parser() = 0;
  245.  
  246. protected:
  247.   /** Constructs a Parser object.
  248.    * Note that Markup::Parser is an abstract class which can't be instantiated
  249.    * directly.  To implement the parser for your markup format, derive from
  250.    * Markup::Parser and implement the virtual methods.
  251.    */
  252.   Parser();
  253.  
  254.   /** Called for open tags <tt>\<foo bar="baz"\></tt>.
  255.    * This virtual method is invoked when the opening tag of an element is seen.
  256.    * @param context The Markup::ParseContext object the parsed data belongs to.
  257.    * @param element_name The name of the element.
  258.    * @param attributes A map of attribute name/value pairs.
  259.    * @throw Glib::MarkupError An exception <em>you</em> should throw if
  260.    * something went wrong, for instance if an unknown attribute name was
  261.    * encountered.  In particular the MarkupError::UNKNOWN_ELEMENT,
  262.    * MarkupError::UNKNOWN_ATTRIBUTE, and MarkupError::INVALID_CONTENT
  263.    * errors are intended to be thrown from user-implemented methods.
  264.    */
  265.   virtual void on_start_element(ParseContext&        context,
  266.                                 const Glib::ustring& element_name,
  267.                                 const AttributeMap&  attributes);
  268.  
  269.   /** Called for close tags <tt>\</foo\></tt>.
  270.    * This virtual method is invoked when the closing tag of an element is seen.
  271.    * @param context The Markup::ParseContext object the parsed data belongs to.
  272.    * @param element_name The name of the element.
  273.    * @throw Glib::MarkupError An exception <em>you</em> should throw if
  274.    * something went wrong, for instance if an unknown attribute name was
  275.    * encountered.  In particular the MarkupError::UNKNOWN_ELEMENT,
  276.    * MarkupError::UNKNOWN_ATTRIBUTE, and MarkupError::INVALID_CONTENT
  277.    * errors are intended to be thrown from user-implemented methods.
  278.    */
  279.   virtual void on_end_element(ParseContext& context, const Glib::ustring& element_name);
  280.  
  281.   /** Called for character data.
  282.    * This virtual method is invoked when some text is seen (text is always
  283.    * inside an element).
  284.    * @param context The Markup::ParseContext object the parsed data belongs to.
  285.    * @param text The parsed text in UTF-8 encoding.
  286.    * @throw Glib::MarkupError An exception <em>you</em> should throw if
  287.    * something went wrong, for instance if an unknown attribute name was
  288.    * encountered.  In particular the MarkupError::UNKNOWN_ELEMENT,
  289.    * MarkupError::UNKNOWN_ATTRIBUTE, and MarkupError::INVALID_CONTENT
  290.    * errors are intended to be thrown from user-implemented methods.
  291.    */
  292.   virtual void on_text(ParseContext& context, const Glib::ustring& text);
  293.  
  294.   /** Called for strings that should be re-saved verbatim in this same
  295.    * position, but are not otherwise interpretable.
  296.    * This virtual method is invoked for comments, processing instructions and
  297.    * doctype declarations; if you're re-writing the parsed document, write the
  298.    * passthrough text back out in the same position.
  299.    * @param context The Markup::ParseContext object the parsed data belongs to.
  300.    * @param passthrough_text The text that should be passed through.
  301.    * @throw Glib::MarkupError An exception <em>you</em> should throw if
  302.    * something went wrong, for instance if an unknown attribute name was
  303.    * encountered.  In particular the MarkupError::UNKNOWN_ELEMENT,
  304.    * MarkupError::UNKNOWN_ATTRIBUTE, and MarkupError::INVALID_CONTENT
  305.    * errors are intended to be thrown from user-implemented methods.
  306.    */
  307.   virtual void on_passthrough(ParseContext& context, const Glib::ustring& passthrough_text);
  308.  
  309.   /** Called on error, including one thrown by an overridden virtual method.
  310.    * @param context The Markup::ParseContext object the parsed data belongs to.
  311.    * @param error A MarkupError object with detailed information about the error.
  312.    */
  313.   virtual void on_error(ParseContext& context, const MarkupError& error);
  314.  
  315. private:
  316.   // noncopyable
  317.   Parser(const Parser&);
  318.   Parser& operator=(const Parser&);
  319.  
  320. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  321.   friend class Glib::Markup::ParserCallbacks;
  322. #endif
  323. };
  324.  
  325.  
  326. /** A parse context is used to parse marked-up documents.
  327.  * @ingroup Markup
  328.  * You can feed any number of documents into a context, as long as no errors
  329.  * occur; once an error occurs, the parse context can't continue to parse text
  330.  * (you have to destroy it and create a new parse context).
  331.  */
  332. class ParseContext : public sigc::trackable
  333. {
  334. public:
  335.   /** Creates a new parse context.
  336.    * @param parser A Markup::Parser instance.
  337.    * @param flags Bitwise combination of Markup::ParseFlags.
  338.    */
  339.   explicit ParseContext(Parser& parser, ParseFlags flags = ParseFlags(0));
  340.   virtual ~ParseContext();
  341.  
  342.   /** Feed some data to the ParseContext.
  343.    * The data need not be valid UTF-8; an error will be signalled if it's
  344.    * invalid. The data need not be an entire document; you can feed a document
  345.    * into the parser incrementally, via multiple calls to this function.
  346.    * Typically, as you receive data from a network connection or file, you feed
  347.    * each received chunk of data into this function, aborting the process if an
  348.    * error occurs. Once an error is reported, no further data may be fed to the
  349.    * ParseContext; all errors are fatal.
  350.    * @param text Chunk of text to parse.
  351.    * @throw Glib::MarkupError
  352.    */
  353.   void parse(const Glib::ustring& text);
  354.  
  355.   /** Feed some data to the ParseContext.
  356.    * The data need not be valid UTF-8; an error will be signalled if it's
  357.    * invalid. The data need not be an entire document; you can feed a document
  358.    * into the parser incrementally, via multiple calls to this function.
  359.    * Typically, as you receive data from a network connection or file, you feed
  360.    * each received chunk of data into this function, aborting the process if an
  361.    * error occurs. Once an error is reported, no further data may be fed to the
  362.    * ParseContext; all errors are fatal.
  363.    * @param text_begin Begin of chunk of text to parse.
  364.    * @param text_end End of chunk of text to parse.
  365.    * @throw Glib::MarkupError
  366.    */
  367.   void parse(const char* text_begin, const char* text_end);
  368.  
  369.   /** Signals to the ParseContext that all data has been fed into the parse
  370.    * context with parse(). This method reports an error if the document isn't
  371.    * complete, for example if elements are still open.
  372.    * @throw Glib::MarkupError
  373.    */
  374.   void end_parse();
  375.  
  376.   /** Retrieves the name of the currently open element.
  377.    * @return The name of the currently open element, or <tt>""</tt>.
  378.    */
  379.   Glib::ustring get_element() const;
  380.  
  381.   /** Retrieves the current line number.
  382.    * Intended for use in error messages; there are no strict semantics for what
  383.    * constitutes the "current" line number other than "the best number we could
  384.    * come up with for error messages."
  385.    */
  386.   int get_line_number() const;
  387.  
  388.   /** Retrieves the number of the current character on the current line.
  389.    * Intended for use in error messages; there are no strict semantics for what
  390.    * constitutes the "current" character number other than "the best number we
  391.    * could come up with for error messages."
  392.    */
  393.   int get_char_number() const;
  394.  
  395.   Parser*       get_parser()       { return parser_; }
  396.   const Parser* get_parser() const { return parser_; }
  397.  
  398. #ifndef DOXYGEN_SHOULD_SKIP_THIS
  399.   GMarkupParseContext*       gobj()       { return gobject_; }
  400.   const GMarkupParseContext* gobj() const { return gobject_; }
  401. #endif
  402.  
  403. private:
  404.   Markup::Parser*       parser_;
  405.   GMarkupParseContext*  gobject_;
  406.  
  407.   // noncopyable
  408.   ParseContext(const ParseContext&);
  409.   ParseContext& operator=(const ParseContext&);
  410.  
  411.   static void destroy_notify_callback(void* data);
  412. };
  413.  
  414. } // namespace Markup
  415.  
  416. } // namespace Glib
  417.  
  418.  
  419. #endif /* _GLIBMM_MARKUP_H */
  420.  
  421.